Thank you for taking the trouble to try this program out. We hope you like it.
Note: this file is formatted and is best read with SimpleText and not TeachText.
Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please donユt modify this file or distribute modified versions.
Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures donユt appear, you can make them appear by scrolling up a page and then back down a page.
This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed.
Contents
The documentation for IIe comes in 4 files. Their contents are:
1. Read me first
What is it? - description, features, requirements, compatibilty, and performance issues
Description
Features
Hardware and software requirements
Compatibility
Performance issues
Installation and setup
Simple installation/setup
Tips
Frequently Asked Questions (FAQ)
2. Instructions
The Apple //e window
The display area
The //e screen
The icon buttons
Function keys
Graphics modes
Disk inserting/removing
Using real disks
Using disk images
How to insert and remove disks and disk images
Loading and saving information - memory images
Emulator instructions
Default settings
Starting up the emulator
The Reset key
The Keyboard
Paddles and buttons
Debugger instructions
3. Configuring IIe
General pane
65c02 pane
Memory pane
Video pane
Sound pane
Keyboard pane
Input devices pane
Disks pane
Slots pane
4. Other stuff
Cost/fee and registration
Version history
Future version features
Distribution
Contacting the author
Other software by Vincent
Disclaimer
2. Instructions
Itユs assumed that you know how to use an Apple II computer. That is, youユre aware of how to switch it on, insert a disk, boot a disk, remove a disk, use the keyboard and use the joystick. If you know these things then youユll find using IIe virtually the same as using an Apple //e except that the disk メinsertionモ and メremovalモ activities are virtual instead of real (unless you insert a real floppy disk into your Mac in which case itユs real - hmmm, are you confused yet?).
If you donユt know how to use an Apple II, just try using IIe anyway, but please donユt send e-mail asking for this kind of help. Instead, trying posting a message to an Apple II message board. Be polite and explain your ignorance of the Apple II. There should be some kind soul to help you out. If youユre on the internet, try the USENET newsgroups such as ヤcomp.sys.apple2.<something>ユ or ヤcomp.emulators.apple2ユ.
The following instructions pertain only to features specific to this emulator.
The Apple //e window
ハ
This window is divided into several areas:
The display area
At the top is the status display area. It shows you the disk drive lights and which slot/drive they belong to and what image files you have loaded into them. To insert or remove a disk, you can click the Insertノ and Removeノ icons on the right side of the window. With more cards installed in the //e, you will see more icons and names in this area (2 for the UniDisk/Hard Disk card, 1 for the memory card, 1 for the MacProDOS card). At the bottom right of the status area is the Soft caps lock status line. You can activate the Soft caps lock feature from the IIe Preferences window (see the document メ3. Configuring IIeモ for instructions on how to do this).
The //e screen
At the bottom left, of course, is the //eユs display area which does the function of a real //eユs video monitor. You cannot select anything in this area but you can copy the contents of the //e screen to the Mac clipboard from the Edit menu.
The icon buttons
At the bottom right are eight useful icons to make it easier for you to use IIe. They are:
・ メInsertノ F5モ lets you select disk images, memory images, and folders for use in a //e drive
・ メRemoveノ F6モ lets you remove a disk image from a //e drive. Note that if you insert a disk image into a drive that already has a disk image in it, the old image is closed first.
・ メResetモ simulates a press of the //eユs reset key (you can also achieve the same effect by pressing control-delete on your Mac keyboard). This icon is disabled is the //e is off or not running).
・ メGo F15モ or メStop F15モ starts and stops the //e (freezes and runs it). This icon can also function as an on/off switch such that clicking it would be the same as turning off a real //e. When configured in this manner, it will be displayed as メOn F15モ and メOff F15モ. See the メ3. Configuring IIeモ for instructions on how to configure it to do this.
・ メPrefsノ F7モ opens the IIe Preferences window. If it has not been previously opened, it is opened at the top-most pane, otherwise it is opened at the most recent pane.
・ メSlotsノモ opens the IIe Preferences window at the Slots pane to let you change the slots. However, changing the slots will not take effect until you quit IIe and start it up again.
・ メMono F13モ and メColour F13モ changes the screen display from monochrome to colour and vice versa. You can also option-click the icon to change depths from 8 -> 1 bit depth, 1 -> 4 bit depth, and 4 -> 8 bit depth. You can also control-click it to change the display: if youユre in monochrome mode, it changes the monochrome-white colour from white -> green, green -> amber, amber -> white; if youユre in colour mode, it does nothing except in double hires mode in which case it will display a sharpened image (but this mode is slower than the normal unsharpened image).
・ メInterruptモ halts the emulation at whatever instruction it is currently at and displays that in the debugger window. Donユt use this icon unless you really need to, or unless you know what you are doing. Why use it? Well itユs handy if you know 65c02 assembly and want to see what the processor is doing. Eg, メis it hanging or still reading the disk? I know! Iユll check by interrupting it!モ Warning: the debugger window is still in development and as such is still very much メrawモ in its functioning.
Function keys
If you have an extended keyboard, you can also use the F-keys at the top of the keyboard. There are 15 such keys, numbered 1 to 15. Their functions are:
・ F3: this is the same as selecting メCopyモ from the Edit menu. It will copy the //e screen to the clipboard (including text if in text mode).
・ F5: this is the same as selecting メInsert Diskノモ from the File menu or clicking the メInsertノモ icon.
・ F6: this is the same as selecting メRemove Diskノモ from the File menu or clicking the メRemoveノモ icon.
・ F7: this is the same as selecting メPreferencesノモ from the File menu or clicking the メPrefsノモ icon.
・ F8: this is the same as selecting メSave IIe Imageノモ from the File menu.
・ F9: step over instruction (active only when the debugger window is active).
・ F10: step into instruction (active only when the debugger window is active).
・ F11: step out of instruction (active only when the debugger window is active).
・ F12: if the debugger window is not active (the emulator is running and is not being debugged) then this key will interrupt the emulator and control is handed to the debugger - it functions as if you had clicked the Interrupt button. If however the debugger window is active, then F8 will function as if you had clicked the Run button in the debugger window. The overall effect is to alternatively interrupt and execute the CPU.
・ F13: this is the same as selecting メMono/Colourノモ from the File menu or clicking the メMono/colourノモ icon. You can also use the option and control keys to select extra options (see Graphics modes below)
・ F15: this is the same as clicking the メpower switchモ icon. Depending on what option the power switch is set to, it will either halt/run the emulator or power-on/power-off the emulator.
Graphics modes
・ IIe shows you the //eユs screen in a Mac window. This window should always be located on the same screen as your menu bar. If you have more than one monitor connected, please do not drag the window to a different monitor because IIe does not support multiple monitors.
・ normal 40 column text, 40 column lores and メnormalモ hires graphics can be displayed in either a small 280 * 192 area or in a larger 560 * 384 area. You can alternate between the two sizes by clicking the windowユs zoom box.
・ 80 column text, 80 column lores and double hires graphics must be displayed in the large 560 * 384 window. You cannot switch to a smaller display whilst any of these modes are active, and activating any of these modes (such as メPR#3 [return]モ from BASIC) will make the emulator switch to the larger size.
・ clicking the mono/colour icon button changes the display of hires graphics and double hires graphics from monochrome to colour and vice versa. It does not affect text or lores graphics. Naturally, this button does nothing if your Macユs monitor is set to display black-and-white (1 bit depth).
・ clicking the mono/colour icon button whilst holding down the option key changes the depth of the Mac monitor. The depth is rotated from 256 colours (8-bit) to black-and-white (1-bit) to 16 colours (4-bit) and then back to 256 colours (8-bit).
・ clicking the mono/colour icon button whilst holding down the control key changes the colour of the monochrome colour. Text is displayed in this colour and so will be affected, as will hires graphics and double hires graphics if the display is set to monochrome (by clicking the mono/colour icon button by itself). Note: control-clicking the icon does nothing if your Macユs monitor is set to display black-and-white (1 bit depth).
Disk inserting/removing
You can insert different kinds of disks into IIeユs メdrivesモ. They can be real 3 1/2" disks, real ProDOS SCSI hard disk partitions, or disk images - a (Mac) file that メcontainsモ an Apple II メdiskモ.
Using real disks
Inserting a real 3 1/2" disk
To use a real 3 1/2" disk, run IIe and when the メApple //eモ window is the front window, insert your 3 1/2" disk into any Mac drive. You will be asked if you wish to メinsertモ the disk into a メdriveモ, and if so, to select which メdriveモ to insert it into. Select your drive and youユre set to use that disk.
Note that although you can insert a Mac formatted disk into the disk drive and then have IIe メinsertモ it into one of its drives, it wonユt be very useful. For all practical purposes, you should insert a ProDOS formatted disk into IIeユs drive (see below for info about ProDOS). If you wish to transfer ProDOS files that are on a Mac floppy disk for use in IIe, you should use the メMacProDOS diskモ peripheral which allows you to transfer files on a Mac disk or folder directly into ProDOS running on the //e.
Inserting a real ProDOS SCSI hard disk partition
To use a real disk, run IIe. If you have configured a UniDisk into one of the //eユs slots and you have a real ProDOS SCSI hard disk partition on your hard disk, you will usually be asked if you wish to メinsertモ that ProDOS SCSI hard disk partition into a メdriveモ, and if so, to select which メdriveモ to insert it into. Select your drive and youユre set to use that disk.
Using disk images
Introduction
To use a disk image, you need to prepare the file properly before you can メinsertモ it into a IIe メdriveモ. A short description of why this is necessary and how to do this follows.
On the Apple II, there are 2 main file systems: DOS 3.3, an older format (and probably the more commoner of the two) which usually supports only 5 1/4" disks; and ProDOS, the newer system which supports different sized disks. The order and format of data on these two systems are completely different from each other, and therefore disk images of disks in these systems are completely different in order and format from each other. As well, there is another file system called Apple Pascal, but isnユt used much (Wizardry is probably the most famous program that used it).
5 1/4" disk images
Most of the disk images of 5 1/4" disks that are available on the internet are in メDOS 3.3モ order and are stored as plain compressed (usually gzipped) binary files. They usually have a メ.dskモ suffix and are usually 143360 bytes when decompressed. So a typical file is stored as ヤcoolgame.dsk.gzユ. This is for the benefit of PC users. When you download such a file to your Mac and decompress it, the file is usually of the wrong Macintosh file type and creator (for example, StuffIt Expander decompresses such files to SimpleText text files: type ヤTEXTユ, creator ヤttxtユ). To use the disk image file with IIe, you need to change the type to one that IIe can use. The fileユs type should be changed to ヤDSK5ユ and its creator to ヤAIIeユ. When you do this, the file can be double clicked and then opened by IIe.
Dos 3.3 ordered 5 1/4" disk images can also have a suffix of メ.doモ. Again, change their type/creator to ヤDSK5ユ/ヤAIIeユ.
The other possible formats for 5 1/4" disks are:
・ メProDOSモ order, usually with a メ.poモ or メ.diskモ suffix. Like Dos 3.3 order disks, they are 143360 bytes long. Change their type/creators to ヤDISKユ/ヤAIIeユ for use in IIe, and
・ メnibbleモ format. These images are usually 232960 bytes long. For example, another Apple II emulator for the Mac called メStopTheMadnessモ saves to disk images only in メnibbleモ format. To use them with IIe, change their type/creators to ヤNIBBユ/ヤAIIeユ.
3 1/2" disk images
Most of the 3 1/2" disk images are similar to the 5 1/4" disk images except that they are usually in メProDOSモ order. Aside from that, they are usually stored as plain compressed (usually gzipped) binary files. Again, they usually have a メ.dskモ suffix. Again, theyユll have the wrong Macintosh file type and creator. To use the disk image file with IIe, you need to change the type to ヤDSK3ユ and its creator to ヤAIIeユ. When you do this, the file can be double clicked and then opened by IIe.
For Mac users, a convenient format for 3 1/2" disks is the Apple Disk Copy format. This is the format that is created by disk imaging software such as Appleユs Disk Copy 4.2 or Chad Magendanzユs ShrinkWrap. Such disk images have メProDOSモ ordering. This format is different to the メplainモ 3 1/2" disk image that is usually found on the internet. Disk Copy images have an extra 84 bytes of data at the beginning of the image to identify the imageユs format. Disk images in this format have the file type ヤdImgユ. This does not need to be changed for IIe to use them: you can drag and drop those files onto IIeユs icon. However, if you want to be able to double click the disk image and have IIe open it, youユll need to change itユs creator to ヤAIIeユ. The nice thing about this format is that you can mount these files on your Mac desktop if you have メProDOS File Systemモ or メPC Exchangeモ installed: you drag and drop the image on top of メShrinkWrapモ or メDropDiskモ and it will mount on your desktop. You can modify the image if you mount if with メShrinkWrapモ but not メDropDiskモ.
Note that DiskCopy images that are modified by IIe can be written out to real 3 1/2" disks with DiskCopy - the checksums are updated when you remove the disk image from the drive or when you quit IIe.
Hard disk images
Finally, there are disks stored in hard disk volume format. They usually have a メ.hdvモ suffix. They are ProDOS ordered files and are usually images of Apple II hard disks. They arenユt common but are supported nonetheless. They have a file type ヤHDV ユ (note the space at the end). Change the fileユs creator to ヤAIIeユ so you can double click them into IIe.
Changing file types and creators
To change a fileユs type or creator, use a file type editor such as ResEdit (free from Apple), BunchTyper (free), FileTyper (shareware), or Aladdinユs Desktop Tools (good quality commercial utility [biased opinion]).
How to insert and remove disks and disk images
After the disk image file is set up for use, you can drag it to IIe or just double click if itユs creator is set to ヤAIIeユ. You can also select メInsert Disk Imageノモ from the File menu or click the メInsertノモ icon button. IIe will then ask you which //e slot and drive to insert the disk into. IIe supports two 5 1/4" drives and two 3 1/2" drives for each installed disk drive メcardモ.
You can remove disks by selecting メRemove Disk Imageノモ from the File menu or click the メRemoveノモ icon button. In the dialog that appears, select which disks you want to remove and click Remove. Note that you do not need to remove a disk before inserting a new one; newly inserted disks displace disks that are already in that drive (that is, the old one is automatically removed for you).
Loading and saving information - memory images
The best way to load and save your data is by saving it to a disk or disk image, which is done by selecting the save command in the Apple II program. However, there are some programs that donユt let you save but there are times that you need to save what youユre doing and return to it later - for example, youユve spent the last 3 hours playing Lode Runner and you a wedding to go to. To solve this problem, IIe allows you to save its current state by the use of メmemory imagesモ. In a nutshell, this operation takes a メsnapshotモ of the //eユs memory and saves it on disk, where it can later be restored.
Note that the size of the saved image will be the size of the current //e memory including any extra auxilary memory you have allocated to the RamWorks III card. So if you have set up a //e with 1 Mb of auxilary memory, the saved image will be 64K (main memory) + 1024K (aux memory). IIe will not save the contents of any Memory Card you install in a slot however.
When you ask IIe to load a memory image, it first checks that the size of the saved image is the same as the current memory setup. If it is, it loads it in and restores the //e to the saved state. Of course, you lose whatever you had in the //eユs memory. You will not be warned of this loss because IIe assumes you know what youユre doing when you open the memory image. If the memory imageユs size does not match the current memory setup, then IIe will offer to load in only the first 128K or to cancel the load operation, and it will tell you what you need to set the memory size to if you want to load the whole image.
Emulator instructions
This section covers topics related to the use of the emulator and its peripherals.
Default settings
The default settings for IIe are:
・ small screen
・ no change in depth
・ colour mode
・ does not draw directly to your screen
・ 1MHz speed
・ 64K only of auxillary memory
・ produces soft sounds
・ no ヤdeleteユ key translation
・ no type-ahead buffer
・ soft caps lock disabled
・ joystick emulation via the keypad
・ fast disk reads and writes
・ ask what to do if a ProDOS hard disk is found
・ the default Mac-ProDOS folder is the folder that the IIe program is in
・ Disk II in slot 6 (fixed)
・ 80 column card in slot 3 (fixed)
・ no other cards installed
Starting up the emulator
If you start IIe with a disk (by double clicking the disk imageユs icon or by dragging it to IIeユs program icon), the emulator will start running as soon as it is ready and the disk is メinsertedモ.
However, when you start IIe without any disks in any drive, the emulator wonユt run until you tell it to. You can start it up by clicking the メRun/Stopモ icon button. Pressing it again will stop it. Alternatively, you can press F15. The icon will change to show you the state of the emulator. Of course, it isnユt very useful without a diskノ
Bonus: if you start IIe up with the command key held down, then IIe will use the title of the //e window to show you how many 65c02 clock cycles it has emulated in each of its emulation cycles (which are about half a second long).
The Reset key
To メresetモ the //e, that is, simulate the pressing of the reset key on a real //e, press control-delete (the delete key here acting like the reset key) or the メResetモ icon button. Tip: to force a メcoldモ reboot, press command-control-delete or command-click the メResetモ icon button. If you want to see the //e diagnostic test, press option-control-delete (or option-click the メResetモ icon button) (but the test is kind of boring in my opinionノ)
The Keyboard
When the emulator is running, all keystrokes are directed to the //e window. When the emulator is not running, all keystrokes are directed to the IIe program, that is, the menu bar or the frontmost window. So if you press command-I to insert a new disk and nothing happens, be sure that the emulator is not running. If it is running, press control-esc or F15 or the メRun/Stopモ icon button, to first halt it and then press command-I (or just click the メInsertノモ icon button if you donユt want to stop the emulator).
The ヤdeleteユ key on the Mac keyboard can be configured to produce either a ヤbackspaceユ or a ヤdeleteユ key on the //e.
IIe implements a type-ahead buffer so you wonユt lose keystrokes but some programs (especially games) donユt respond with this on so you may have to turn it off. For text editors and word processors, youユll probably want to turn it on.
The Tab key can be configured as a ヤsoft caps lockユ key. If configured as such, then when you first press it, it changes any key you type from uppercase to lowercase and vice versa. When pressed again, it does not change the keys. In other words, it acts just like the real ヤcaps lockユ key but the changes apply only to //e. This allows you to keep the real ヤcaps lockユ key in your preferred position without having to change it every time you use another Mac program.
Paddles and buttons
The paddles/joystick is emulated by the use of either the Mac keypad or the mouse. If you have a joystick or gamepad attached to your Mac, you should set it to simulate the keypad.
If the keypad is selected to emulate the joystick, then:
・ Keypad 7 is the same as pushing the joystick to the top-left
・ Keypad 3 is the same as pushing it to the bottom-right
・ Keypad 1 pushes it to the bottom-left
・ Keypad 9 pushes it to the top-right
・ The other keypad keys push it in between the corners
Iユve found that this arrangements works quite well - most programs Iユve tried it with have no problems with it.
If the mouse is selected to emulate the joystick, then moving the mouse around the screen will move the joystick in the same direction. You can configure the mouse paddle values to be based on the mouseユs screen position or its position within the //e window.
This emulator uses a メsmartモ paddle emalation routine (technical weenies: it counts clock cycles), so all paddle/joystick reading programs should work. If you find a program that doesnユt work well, let me know and Iユll investigate it.
The メopenモ and メclosedモ apple keys on the //e keyboard (paddle 0ユs button and paddle 1ユs button respectively), as well as the third paddle button are supported. The Mac keys to use are command, option and shift respectively.
Debugger instructions
Important: most people will not need to read this section for ordinary use of IIe. This section covers the use of the debugger which is a tool for seeing what the //e is doing at the machine instruction level.
If you end up in the debugger and donユt know what to do, try clicking the Run button. If it fails, try clicking the Reset button. If that fails, youユll have to power down the //e or quit IIe and restart it.
Currently the debugger is in a メrawモ state, ie, incomplete and rough at the edges. However, you can use it to do some interesting things such as:
・ set a breakpoint
・ step an instruction
・ step over an instruction
・ step over all instructions in a loop and stop at the end of a loop
・ step over all instructions in a 65c02 subroutine and stop at the point after the caller routine called the subroutine
・ break on interrupts
・ reset the //e
・ run the //e
・ disassemble memory
・ change memory and the 65c02 registers
Oops. Iユll get around to writing this section for the next release. Letユs say that learning about the debugger メis left as an exercise for the readerモ :-)